home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 November / SGI Freeware 1999 November - Disc 1.iso / dist / fw_cvs.idb / usr / freeware / info / cvsclient.info-3.z / cvsclient.info-3 (.txt)
GNU Info File  |  1999-04-16  |  11KB  |  210 lines
  1. This is Info file cvsclient.info, produced by Makeinfo version 1.67
  2. from the input file ./cvsclient.texi.
  3. File: cvsclient.info,  Node: Example,  Next: Requirements,  Prev: Text tags,  Up: Protocol
  4. Example
  5. =======
  6.    Here is an example; lines are prefixed by `C: ' to indicate the
  7. client sends them or `S: ' to indicate the server sends them.
  8.    The client starts by connecting, sending the root, and completing the
  9. protocol negotiation.  In actual practice the lists of valid responses
  10. and requests would be longer.
  11.      C: Root /u/cvsroot
  12.      C: Valid-responses ok error Checked-in M E
  13.      C: valid-requests
  14.      S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
  15.      S: ok
  16.      C: UseUnchanged
  17.    The client wants to check out the `supermunger' module into a fresh
  18. working directory.  Therefore it first expands the `supermunger'
  19. module; this step would be omitted if the client was operating on a
  20. directory rather than a module.
  21.      C: Argument supermunger
  22.      C: Directory .
  23.      C: /u/cvsroot
  24.      C: expand-modules
  25.    The server replies that the `supermunger' module expands to the
  26. directory `supermunger' (the simplest case):
  27.      S: Module-expansion supermunger
  28.      S: ok
  29.    The client then proceeds to check out the directory.  The fact that
  30. it sends only a single `Directory' request which specifies `.' for the
  31. working directory means that there is not already a `supermunger'
  32. directory on the client.
  33.      C: Argument -N
  34.      C: Argument supermunger
  35.      C: Directory .
  36.      C: /u/cvsroot
  37.      C: co
  38.    The server replies with the requested files.  In this example, there
  39. is only one file, `mungeall.c'.  The `Clear-sticky' and
  40. `Clear-static-directory' requests are sent by the current
  41. implementation but they have no effect because the default is for those
  42. settings to be clear when a directory is newly created.
  43.      S: Clear-sticky supermunger/
  44.      S: /u/cvsroot/supermunger/
  45.      S: Clear-static-directory supermunger/
  46.      S: /u/cvsroot/supermunger/
  47.      S: E cvs server: Updating supermunger
  48.      S: M U supermunger/mungeall.c
  49.      S: Created supermunger/
  50.      S: /u/cvsroot/supermunger/mungeall.c
  51.      S: /mungeall.c/1.1///
  52.      S: u=rw,g=r,o=r
  53.      S: 26
  54.      S: int mein () { abort (); }
  55.      S: ok
  56.    The current client implementation would break the connection here
  57. and make a new connection for the next command.  However, the protocol
  58. allows it to keep the connection open and continue, which is what we
  59. show here.
  60.    After the user modifies the file and instructs the client to check it
  61. back in.  The client sends arguments to specify the log message and file
  62. to check in:
  63.      C: Argument -m
  64.      C: Argument Well, you see, it took me hours and hours to find
  65.      C: Argumentx this typo and I searched and searched and eventually
  66.      C: Argumentx had to ask John for help.
  67.      C: Argument mungeall.c
  68.    It also sends information about the contents of the working
  69. directory, including the new contents of the modified file.  Note that
  70. the user has changed into the `supermunger' directory before executing
  71. this command; the top level directory is a user-visible concept because
  72. the server should print filenames in `M' and `E' responses relative to
  73. that directory.
  74.      C: Directory .
  75.      C: /u/cvsroot/supermunger
  76.      C: Entry /mungeall.c/1.1///
  77.      C: Modified mungeall.c
  78.      C: u=rw,g=r,o=r
  79.      C: 26
  80.      C: int main () { abort (); }
  81.    And finally, the client issues the checkin command (which makes use
  82. of the data just sent):
  83.      C: ci
  84.    And the server tells the client that the checkin succeeded:
  85.      S: M Checking in mungeall.c;
  86.      S: E /u/cvsroot/supermunger/mungeall.c,v  <--  mungeall.c
  87.      S: E new revision: 1.2; previous revision: 1.1
  88.      S: E done
  89.      S: Mode u=rw,g=r,o=r
  90.      S: Checked-in ./
  91.      S: /u/cvsroot/supermunger/mungeall.c
  92.      S: /mungeall.c/1.2///
  93.      S: ok
  94. File: cvsclient.info,  Node: Requirements,  Next: Obsolete,  Prev: Example,  Up: Protocol
  95. Required versus optional parts of the protocol
  96. ==============================================
  97.    The following are part of every known implementation of the CVS
  98. protocol (except obsolete, pre-1.5, versions of CVS) and it is
  99. considered reasonable behavior to completely fail to work if you are
  100. connected with an implementation which attempts to not support them.
  101. Requests: `Root', `Valid-responses', `valid-requests', `Directory',
  102. `Entry', `Modified', `Unchanged', `Argument', `Argumentx', `ci', `co',
  103. `update'.  Responses: `ok', `error', `Valid-requests', `Checked-in',
  104. `Updated', `Merged', `Removed', `M', `E'.
  105.    A server need not implement `Repository', but in order to
  106. interoperate with CVS 1.5 through 1.9 it must claim to implement it (in
  107. `Valid-requests').  The client will not actually send the request.
  108. File: cvsclient.info,  Node: Obsolete,  Prev: Requirements,  Up: Protocol
  109. Obsolete protocol elements
  110. ==========================
  111.    This section briefly describes protocol elements which are obsolete.
  112. There is no attempt to document them in full detail.
  113.    There was a `Repository' request which was like `Directory' except
  114. it only provided REPOSITORY, and the local directory was assumed to be
  115. similarly named.
  116.    If the `UseUnchanged' request was not sent, there was a `Lost'
  117. request which was sent to indicate that a file did not exist in the
  118. working directory, and the meaning of sending `Entries' without `Lost'
  119. or `Modified' was different.  All current clients (CVS 1.5 and later)
  120. will send `UseUnchanged' if it is supported.
  121. File: cvsclient.info,  Node: Protocol Notes,  Prev: Protocol,  Up: Top
  122. Notes on the Protocol
  123. *********************
  124.    A number of enhancements are possible.  Also see the file TODO in
  125. the CVS source distribution, which has further ideas concerning various
  126. aspects of CVS, some of which impact the protocol.
  127.    * The `Modified' request could be speeded up by sending diffs rather
  128.      than entire files.  The client would need some way to keep the
  129.      version of the file which was originally checked out; probably
  130.      requiring the use of "cvs edit" in this case is the most sensible
  131.      course (the "cvs edit" could be handled by a package like VC for
  132.      emacs).  This would also allow local operation of `cvs diff'
  133.      without arguments.
  134.    * The current procedure for `cvs update' is highly sub-optimal if
  135.      there are many modified files.  One possible alternative would be
  136.      to have the client send a first request without the contents of
  137.      every modified file, then have the server tell it what files it
  138.      needs.  Note the server needs to do the what-needs-to-be-updated
  139.      check twice (or more, if changes in the repository mean it has to
  140.      ask the client for more files), because it can't keep locks open
  141.      while waiting for the network.  Perhaps this whole thing is
  142.      irrelevant if there is a multisite capability (as noted in TODO),
  143.      and therefore the rcsmerge can be done with a repository which is
  144.      connected via a fast connection.
  145.    * The fact that `pserver' requires an extra network turnaround in
  146.      order to perform authentication would be nice to avoid.  This
  147.      relates to the issue of reporting errors; probably the clean
  148.      solution is to defer the error until the client has issued a
  149.      request which expects a response.  To some extent this might
  150.      relate to the next item (in terms of how easy it is to skip a
  151.      whole bunch of requests until we get to one that expects a
  152.      response).  I know that the kerberos code doesn't wait in this
  153.      fashion, but that probably can cause network deadlocks and perhaps
  154.      future problems running over a transport which is more transaction
  155.      oriented than TCP.  On the other hand I'm not sure it is wise to
  156.      make the client conduct a lengthy upload only to find there is an
  157.      authentication failure.
  158.    * The protocol uses an extra network turnaround for protocol
  159.      negotiation (`valid-requests').  It might be nice to avoid this by
  160.      having the client be able to send requests and tell the server to
  161.      ignore them if they are unrecognized (different requests could
  162.      produce a fatal error if unrecognized).  To do this there should
  163.      be a standard syntax for requests.  For example, perhaps all
  164.      future requests should be a single line, with mechanisms analogous
  165.      to `Argumentx', or several requests working together, to provide
  166.      greater amounts of information.  Or there might be a standard
  167.      mechanism for counted data (analogous to that used by `Modified')
  168.      or continuation lines (like a generalized `Argumentx').  It would
  169.      be useful to compare what HTTP is planning in this area; last I
  170.      looked they were contemplating something called Protocol Extension
  171.      Protocol but I haven't looked at the relevant IETF documents in
  172.      any detail.  Obviously, we want something as simple as possible
  173.      (but no simpler).
  174.    * The scrambling algorithm in the CVS client and server actually
  175.      support more characters than those documented in *Note Password
  176.      scrambling::.  Someday we are going to either have to document
  177.      them all (but this is not as easy as it may look, see below), or
  178.      (gradually and with adequate process) phase out the support for
  179.      other characters in the CVS implementation.  This business of
  180.      having the feature partly undocumented isn't a desirable state
  181.      long-term.
  182.      The problem with documenting other characters is that unless we
  183.      know what character set is in use, there is no way to make a
  184.      password portable from one system to another.  For example, a with
  185.      a circle on top might have different encodings in different
  186.      character sets.
  187.      It *almost* works to say that the client picks an arbitrary,
  188.      unknown character set (indeed, having the CVS client know what
  189.      character set the user has in mind is a hard problem otherwise),
  190.      and scrambles according to a certain octet<->octet mapping.  There
  191.      are two problems with this.  One is that the protocol has no way
  192.      to transmit character 10 decimal (linefeed), and the current
  193.      server and clients have no way to handle 0 decimal (NUL).  This
  194.      may cause problems with certain multibyte character sets, in which
  195.      octets 10 and 0 will appear in the middle of other characters.
  196.      The other problem, which is more minor and possibly not worth
  197.      worrying about, is that someone can type a password on one system
  198.      and then go to another system which uses a different encoding for
  199.      the same characters, and have their password not work.
  200.      The restriction to the ISO646 invariant subset is the best
  201.      approach for strings which are not particularly significant to
  202.      users.  Passwords are visible enough that this is somewhat
  203.      doubtful as applied here.  ISO646 does, however, have the virtue
  204.      (!?) of offending everyone.  It is easy to say "But the $ is right
  205.      on people's keyboards!  Surely we can't forbid that".  From a
  206.      human factors point of view, that makes quite a bit of sense.  The
  207.      contrary argument, of course, is that a with a circle on top, or
  208.      some of the characters poorly handled by Unicode, are on
  209.      *someone*'s keyboard.
  210.